<!DOCTYPE html>
<html lang="en">
    <!--
      Licensed to the Apache Software Foundation (ASF) under one or more
      contributor license agreements.  See the NOTICE file distributed with
      this work for additional information regarding copyright ownership.
      The ASF licenses this file to You under the Apache License, Version 2.0
      (the "License"); you may not use this file except in compliance with
      the License.  You may obtain a copy of the License at
          http://www.apache.org/licenses/LICENSE-2.0
      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    -->
    <head>
        <meta charset="utf-8"/>
        <title>JsonTreeReader</title>
        <link rel="stylesheet" href="/nifi-docs/css/component-usage.css" type="text/css"/>
    </head>

    <body>
        <p>
        	The JsonTreeReader Controller Service reads a JSON Object and creates a Record object for the entire
        	JSON Object tree. The Controller Service must be configured with a Schema that describes the structure
        	of the JSON data. If any field exists in the JSON that is not in the schema, that field will be skipped.
        	If the schema contains a field for which no JSON field exists, a null value will be used in the Record
        	(or the default value defined in the schema, if applicable).
        </p>
        
        <p>
        	If the root element of the JSON is a JSON Array, each JSON Object within that array will be treated as
        	its own separate Record. If the root element is a JSON Object, the JSON will all be treated as a single
        	Record.
        </p>


		<h2>Schemas and Type Coercion</h2>
		
		<p>
			When a record is parsed from incoming data, it is separated into fields. Each of these fields is then looked up against the
			configured schema (by field name) in order to determine what the type of the data should be. If the field is not present in
			the schema, that field is omitted from the Record. If the field is found in the schema, the data type of the received data
			is compared against the data type specified in the schema. If the types match, the value of that field is used as-is. If the
			schema indicates that the field should be of a different type, then the Controller Service will attempt to coerce the data
			into the type specified by the schema. If the field cannot be coerced into the specified type, an Exception will be thrown.
		</p>
		
		<p>
			The following rules apply when attempting to coerce a field value from one data type to another:
		</p>
			
		<ul>
			<li>Any data type can be coerced into a String type.</li>
			<li>Any numeric data type (Byte, Short, Int, Long, Float, Double) can be coerced into any other numeric data type.</li>
			<li>Any numeric value can be coerced into a Date, Time, or Timestamp type, by assuming that the Long value is the number of
			milliseconds since epoch (Midnight GMT, January 1, 1970).</li>
			<li>A String value can be coerced into a Date, Time, or Timestamp type, if its format matches the configured "Date Format," "Time Format,"
				or "Timestamp Format."</li>
			<li>A String value can be coerced into a numeric value if the value is of the appropriate type. For example, the String value
				<code>8</code> can be coerced into any numeric type. However, the String value <code>8.2</code> can be coerced into a Double or Float
				type but not an Integer.</li>
			<li>A String value of "true" or "false" (regardless of case) can be coerced into a Boolean value.</li>
			<li>A String value that is not empty can be coerced into a Char type. If the String contains more than 1 character, the first character is used
				and the rest of the characters are ignored.</li>
			<li>Any "date/time" type (Date, Time, Timestamp) can be coerced into any other "date/time" type.</li>
			<li>Any "date/time" type can be coerced into a Long type, representing the number of milliseconds since epoch (Midnight GMT, January 1, 1970).</li>
			<li>Any "date/time" type can be coerced into a String. The format of the String is whatever DateFormat is configured for the corresponding
				property (Date Format, Time Format, Timestamp Format property). If no value is specified, then the value will be converted into a String
				representation of the number of milliseconds since epoch (Midnight GMT, January 1, 1970).</li>
		</ul>
		
		<p>
			If none of the above rules apply when attempting to coerce a value from one data type to another, the coercion will fail and an Exception
			will be thrown.
		</p>
		
		
        <h2>Examples</h2>
        
        <p>
        	As an example, consider the following JSON is read:
        </p>
<code>
<pre>
[{
    "id": 17,
    "name": "John",
    "child": {
        "id": "1"
    },
    "dob": "10-29-1982"
    "siblings": [
        { "name": "Jeremy", "id": 4 },
        { "name": "Julia", "id": 8}
    ]
  },
  {
    "id": 98,
    "name": "Jane",
    "child": {
        "id": 2
    },
    "dob": "08-30-1984"
    "gender": "F",
    "siblingIds": [],
    "siblings": []
  }]
</pre>
</code>
        
        <p>
        	Also, consider that the schema that is configured for this JSON is as follows (assuming that the AvroSchemaRegistry
        	Controller Service is chosen to denote the Schema:
        </p>

<code>
<pre>
{
	"namespace": "nifi",
	"name": "person",
	"type": "record",
	"fields": [
		{ "name": "id", "type": "int" },
		{ "name": "name", "type": "string" },
		{ "name": "gender", "type": "string" },
		{ "name": "dob", "type": {
			"type": "int",
			"logicalType": "date"
		}},
		{ "name": "siblings", "type": {
			"type": "array",
			"items": {
				"type": "record",
				"fields": [
					{ "name": "name", "type": "string" }
				]
			}
		}}
	]
}
</pre>
</code>
        
        <p>
        	Let us also assume that this Controller Service is configured with the "Date Format" property set to "MM-dd-yyyy", as this
        	matches the date format used for our JSON data. This will result in the JSON creating two separate records, because the root
        	element is a JSON array with two elements.
        </p>
        
        <p>
        	The first Record will consist of the following values:
        </p>
        
        <table>
        	<tr>
    			<th>Field Name</th>
    			<th>Field Value</th>
        	</tr>
    		<tr>
    			<td>id</td>
    			<td>17</td>
    		</tr>
    		<tr>
    			<td>name</td>
    			<td>John</td>
    		</tr>
    		<tr>
    			<td>gender</td>
    			<td><i>null</i></td>
    		</tr>
    		<tr>
    			<td>dob</td>
    			<td>11-30-1983</td>
    		</tr>
    		<tr>
    			<td>siblings</td>
    			<td>
    				<i>array with two elements, each of which is itself a Record:</i>
    				<br />
    				<table>
    					<tr>
							<th>Field Name</th>
							<th>Field Value</th>
						</tr>
						<tr>
							<td>name</td>
							<td>Jeremy</td>
						</tr>
    				</table>
    				<br />
    				<i>and:</i>
    				<br />
    				<table>
						<tr>
							<th>Field Name</th>
							<th>Field Value</th>
						</tr>
						<tr>
							<td>name</td>
							<td>Julia</td>
						</tr>
    				</table>
    			</td>
    		</tr>
        </table>
        
        <p>
        	The second Record will consist of the following values:
        </p>
        
		<table>
			<tr>
    			<th>Field Name</th>
    			<th>Field Value</th>
        	</tr>
    		<tr>
    			<td>id</td>
    			<td>98</td>
    		</tr>
    		<tr>
    			<td>name</td>
    			<td>Jane</td>
    		</tr>
    		<tr>
    			<td>gender</td>
    			<td>F</td>
    		</tr>
    		<tr>
    			<td>dob</td>
    			<td>08-30-1984</td>
    		</tr>
    		<tr>
    			<td>siblings</td>
    			<td><i>empty array</i></td>
    		</tr>
        </table>
        
    </body>
</html>
